ASME's Mechanical Engine…ing Toolkit 1997 December/ASME's Mechanical Engineering Toolkit 1997 December.iso/main_frm/dvidis.zoo/dvidis.doc

Text File | 1989-02-16 | 15KB | 331 lines

        This documentation corresponds to DVIDIS V3.4

            Documentation Version of 6-Apr-88

DVIDIS is a program that displays TeX DVI files on a VaxStation running VWS.

                  N O T E

    If you have used previous versions of DVIDIS, note that this
    version is VERY different.  The human interface is much better,
    but most important, the program now reads PK format font files,
    not the old, very obsolete RST format font files.  It is possible
    to build a version with RST file support, but that hasn't been
    tested and is not recommended.  PK fonts are MUCH better in every
    way.

Basic usage is very simple.  To display file TEXT.DVI, for example, just
type:
        $ DVIDIS TEXT

on your VAXStation.  A large window will be created, and your text should
start to appear in it; depending on the paper size and where you have located
your window (by default it starts out centered), you may be able to see the
"edge" of the paper as a gray bar.  Meanwhile, your keyboard will remain
attached to the window you were previously in, and you can enter commands.
For a list of commands available to you, hit the HELP key.  The effect of
the various commands is easy to see, so experiment until you feel comfortable
with them.

You can also specify a couple of options on the DVIDIS command line.  These
CANNOT be changed once DVIDIS has started.  All options are of the form "-l"
where "l" is any single letter, with the single exception of -verbose (for
historical reasons).  Some are followed - after a space - by one or a pair of
numeric arguments; the -s command must be followed by a paper size specifica-
tion.

For example:

        $ DVIDIS -w -p 2 4 TEXT

means "display pages 2 to 4 of TEXT.DVI in 'wide' mode."

The following options are commonly used:

-c    The fonts that DVIDIS uses are meant for a 300 dpi printer.  A VAXSta-
    tion display has about 78 dpi.  As a result, if you display the glyphs
    from these fonts at a 1-1 pixel-to-pixel mapping, they are about 4
    times as large as they would be on the page, and only about 1/9 of the
    page is visible at a time.  Normally, DVIDIS compresses all fonts by a
    2-to-1 factor.  The fonts are still readable, but you can now get most
    of the width of a page - all, with any reasonable margins - and over
    half the height on the screen.  Specifying "-c" turns off this com-
    pression; it's useful mainly for looking at the glyphs, not the text.

-w    Specifies a 4-to-1 glyph compression factor.  This allows you to see
    how a whole page looks, but unfortunately it's rather hard to read
    the resulting text.

-m    Tells DVIDIS to try to use smaller fonts, rather than compressing
    larger ones.  This only works if you actually HAVE the small fonts on
    your system.  When it works, it improves the appearance of individual
    characters, although it often makes lines come out with slightly
    different lengths than they should.  -m is especially useful in
    conjunction with -w.  -m in conjunction with -c is meaningless.

-s ss    Set the paper size.  This determines what size paper the program
    assumes you are printing on.  The default is "letter", which is
    8.5 x 11 inches.  The argument is the name of a paper size; type
    DVIDIS -s ? for a list of possible values.

    The paper size controls where DVIDIS places a visible gray border,
    and when it tells you that characters have "run off the page".  It
    always displays the characters, however.

    Paper size "huge" is meant for special purposes; using it will make
    many of the commands you can type to DVIDIS while it is running work
    in strange ways.  You should generally avoid using size "huge".

-verbose
    Makes the program talkative.  This is mainly useful for debugging,
    but since it displays all the font files it opens, successfully or
    not, it can be used to determine which files are needed.  The needed
    files can be created if they don't already exist.  They can also be
    put on your workstation's local disk to improve performance.

The rest of the options are rarely used:

-v <mi>, -h <mi>
    Set the vertical (horizonal) margin.  Next argument is the margin, in
    milli-inches.  Default is 1000 milli-inches each, which is the same
    default used by many common DVI printing programs.  If you find a lot
    of "off-screen glyph" errors, and you have the paper size set cor-
    rectly, try changing these parameters.  (Besides 1000, the second
    most common value expected is 0 for both margins.)

    Note that the default corresponds to the current TeX standard.  If
    you find you have to use some other value to make your output look
    right, some other piece of software you are running is obsolete.

-p <s> <e>
    Limits the display to pages <s> through <e> inclusive.  You can only
    specify one page range at a time, but you can specify multiple -p
    options, each specifying a page range.  When you specify page ranges,
    DVIDIS will only "see" pages within the ranges given.  Nothing you
    can do while the program is running will let you display any page
    not within any page range - DVIDIS will simply skip past the pages.

-f    Causes the program to look in "USER$RST" rather than "TEX$RST" for the
    fonts.  This command is meaningless for the PK version of DVIDIS, and
    of little use even in the RST version.

-d    Debug.  Generates a lot of output that's useful only to developers.


Program    Installation

DVIDIS consists of a single image, DVIDIS.EXE, that runs on an VAXStation
with VWS V3.0 or later.  It runs as a normal user-mode image, and needs no
special privileges.  DVIDIS uses a fair amount of memory as it runs, so be
sure to provide a reasonable working set - at least 1200 pages, 2000 or more
is better.  In order for DVIDIS to receive its arguments, it must be started
with a foreign command line, given by something like:

        $ DVIDIS :== $DEV:[DIR]DVIDIS

Two "environment variables" can be set to control DVIDIS, and you can specify
font substitutions.  The environment variables - typically, logicals, but
if no logicals are defined any DCL symbol of the same name will be used -
are:

DVIDIS_FILE_FORMAT
    A string that specifies how to construct a file specification for
    a font file, given a font name and a dots-per-inch value.  The
    font name will be substituted for %s; the dots-per-inch value for
    %d.  You must have EXACTLY one of each, in either order; you may
    NOT have any additional occurences of "%".

    There are two common schemes for storing PK font files:

        One directory, DEV:[DIR], font "name" at "ddd" dots
        per inch is file name.dddPK.  A format string for
        this case would look like "DEV:[DIR]%s.%dPK".

        One root directory, DEV:[DIR.]; fonts at "ddd" dots
        per inch are in subdirectory [.DPIddd], with font
        "name" in name.PK.  A format string for this case
        would look like "DEV:[DIR.DPI%d]%s.PK".

    If DVIDIS_FILE_FORMAT is not defined, the default format string
    is "TEX_FONTS:[DPI%d]%s.PK".  This corresponds to the second way
    of organizing the font files, and assumes that TEX_FONTS is a
    rooted logical translating to something like DEV:[DIR.].

    You can only specify a single file format, but that file format
    could involve a logical that translates to a search list.  For
    example, using the default file format, you might do:

        $ DEFINE TEX_FONTS $DISK1:[TEX.PK.],NODE::TEX_FONTS:

    where "NODE" is the name of a node with more fonts than you are
    willing to store locally.  On NODE, TEX_FONTS must be a SYSTEM
    logical name that translates to a rooted directory.  (If you
    have proxy access to NODE, you could define TEX_FONTS in your
    login file on NODE).  Because of a VMS bug, it isn't possible
    to use something like NODE::DEV:[DIR.] to avoid needing a logical
    name on NODE.  (This bug appears in VMS Version 4.5.  If you
    a more recent version, the bug may have been fixed.)

            I M P O R T A N T   N O T E

    The definition of DVIDIS_FILE_FORMAT will be used as a printf()
    format string.  The "d" and "s" format specifiers MUST be in
    lower case; if you make them upper case, the format will not
    work.  Note also that DCL forces characters to upper case unless
    they are inside a quoted string.  Hence, your definition should
    look something like:

        $ DEFINE DVIDIS_FILE_FORMAT "TEX_FONTS:%s.%dPK"

DVIDIS_FONT_SIZES
    This variable must translate to a list of all dot-per-inch values
    at which you have any fonts available.  The list consist of just
    the numbers (the "ddd" values discussed above), separated by
    commas.  DVIDIS will never find a font at a size not given in
    the list.

    The default list is:

        100,121,145,174,180,208,210,225,240,250,263,270,274,
        300,329,360,432,518,622,746,895,896,1074,1075,1289,
        1290,1547,1548

    which is the list of values I've got.  Extra values will slow
    DVIDIS down a bit when it has to open a file, but not by much,
    so you can use the default unless you have some sizes I don't.

    Note that this list is NOT a search list, use:

        $ DEFINE DVIDIS_FONT_SIZES "300,329,360"

    WITH THE QUOTATION MARKS.  If you leave the quotation marks off,
    DVIDIS will never use anything but the first value you list.


Font Substitution

If DVIDIS is unable to find a font as specified, it will check to see if you
have defined a substitute for it in any of three substitution files.  If you
are displaying file jobname.DVI, the files are:

        jobname.SUB        in the same directory as jobname.DVI;
        TEXFONTS.SUB        in the current directory;
        TEX$INPUTS:TEXFONTS.SUB

Every time a substitution is needed, the files present are checked, in the
order given, each from beginning to end, to try to find a substitute.  Only
the first match is used, however.

Each of the substitution files has the same format.  It's a simple ASCII file,
with one substitution per line.  Comments, as in TeX, are introduced by "%"
and continue to the end of the line.

A substitution line has either of two forms:

    oldname.oldsize -> subname.subsize
    oldname            -> subname

The first format substitutes only for a particular font name and size.  The
second format substitutes for a particular font name at any size.

Spaces can be used freely in substitution lines.

Since only the first match is used, and the files are always read from the
first line onward, you should specify particular substitutions - those with
a size - before generic ones.

It's not an error for the substituted font file not to be found - DVIDIS will
proceed to look for "nearby" fonts, possibly substituting for them as well.

The DVIDIS distribution includes a TEXFONTS.SUB file that substitutes CM fonts
for AM fonts.  This should allow you to display DVI files created using older
versions of TeX.


Getting the Find and Remove Keypad Keys to Work

The Find and Remove keypad keys use OSC functions to control the terminal
window.  OSC's must be enabled; from questions I've received, it seems that
many people are not enabling them.  To enable OSC's, issue the following
command from DCL (in a privileged account):

    $ DEFINE/SYSTEM/EXEC UIS$VT_ENABLE_OSC_STRINGS TRUE


Known Bugs and Restrictions

DVIDIS is intended to report an error if it can't find a "close" match to a
font called for in the file it is displaying.  The test it makes for "close-
ness" is wrong, however, so it currently almost never reports a problem.  The
result may be grossly distorted output, with no indication that the problem
isn't in the file, it's that DVIDIS had to chose an inappropriate font.

Characters actually appearing in the font file, but with no pixels (i.e., a
"0 by 0" raster) cause DVIDIS to crash.  This is known to occur with the
CMAPL10 font (at least character '040 is a "space") and probably will occur
with any of the LaTeX "invisible" slide fonts.

Stanford Version 2.2 of PXTOPK, and all distributed versions to date of
Kellerman and Smith's PXTOPK for VMS, have distinct bugs that produce com-
pletely invalid PK files.  Files produced using the Stanford V2.2 code can
be recognized by using PKTYPE and looking at the X-offset and Y-offset values
for a couple of characters.  Typical values are small positive or negative
integers - values outside the range -30 to 30 are very unlikely.  The V2.2
code will produce random, often very large, values.  I don't know the exact
symptoms of the problems the Kellerman and Smith code will produce.  See the
article by Dan Hosek in TeXhax, Volume 88, #24 for a discussion.  Version 2.3
of PXTOPK fixes the underlying problem; both PXTOPK.WEB and a corresponding
version of PXTOPK.VMS-CHANGES should be available from "the usual sources",
or from the same place you got DVIDIS, if all else fails.

DVIDIS uses the dx field of PK fonts to determine the width of the characters
it displays.  Width information can also be obtained from the "TFM width"
field.  It seems that most commonly-used DVI file drivers use the TFM width.
As a result, bugs that result in PK files with invalid dx values can go
undetected for years.  The most common case, easily detectable with PKTYPE,
will have dx=0 for all the characters.  When such a font is displayed, what
you'll see is bunches of characters displayed at the same position; since
inter-word spacing doesn't depend on the dx values, you'll see one "blotch"
per word.  One place I've seen this come up is with the Hebrew fonts that
come with Jacques Goldberg's SemiTeX.  Examination of the GF files reveals
that they have 0 dx values as well, so the problem seems to be some (as-yet
undetermined) inappropriate parameter setting for Metafont.  You can work
around this problem by doing a round-about conversion:  Rather than using
GFTOPK, use GFTOPX (or PKTOPX, if you've already got PK files), then PXTOPK.
PX files don't store the dx value at all, so a CORRECT PXTOPK will re-compute
it.

If DVIDIS_FONT_SIZES specifies exactly one font size, unpredictable results,
including crashes, may occur.  This shouldn't happen under normal circum-
stances, but if you find a distorted display and other odd things happening,
it could be that DVIDIS_FONT_SIZES is set up wrong.  In particular, make sure
that you've defined it to have a single translation that contains a list of
sizes separated by commas, rather than as multiple translations, each of which
is a single size.  This is discussed above.

If the original TeX run specified a magnification value other than 1000, the
spacing will be incorrect.  The only current work-around is to re-run TeX
without the magnification.  Note that this restriction applies only to GLOBAL
magnifications (i.e., uses of \magification).  Individually magnified fonts
are handled correctly.

There is a bug in the VAX C library for Versions 4.6 and 4.7 of VMS that will
cause DVIDIS to die with a Reserved Operand Fault if it runs out of memory.
The only work-around is to increase the amount of virtual memory available
to the process running DVIDIS.  (Note that, without the bug, DVIDIS would
try to recover by discarding some font information it has already read in.
The resulting performance loss would probably be substantial, so you'd
probably want to run with a larger virtual memory limit anyway.  On a work-
station, there is little reason NOT to run this way in any case.  You'll
probably want to allow big working sets, too.)


Author:  Jerry Leichter, based on work of Bill Gropp's, which in turn was
based on a lot of earlier work by others; with additional input from Bert
Beander at DEC.  Comments/questions/suggestions to Jerry Leichter at

        [e-mail]
       or
        [e-mail]